Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Introduction
This document describes the various scenarios part editors must deal with in handling mouse events. Code snippets are not included, but the sample part editors provide additional information, and a thorough understanding of the information here is important to understanding how to implement the OpenDoc human interface.
The Basic Event Handling recipe should be read first. Mouse events in window title bars are converted to window events. See the Window Events recipe. Mouse down events in the menu bar are converted to menu events. See the Menus recipe.
Part editors must handle the following standard mouse events:
kODEvtMouseDown
kODEvtMouseUp
To support dragging from an inactive (background) document, part editors must handle:
kODEvtBGMouseDown // Mouse down in an inactive (background) document
Part editors which support embedding must also handle the following mouse events:
kODEvtMouseDownEmbedded // Mouse down in a selected, bundled or iconic frame
kODEvtBGMouseDownEmbedded // As above, in an inactive (background) document
kODEvtMouseUpEmbedded // Mouse up in a selected, bundled or iconic frame
kODEvtMouseDownBorder // Mouse down in the active frame border
Mouse Event Summary
The following diagram and table represent an attempt to summarize the distribution and handling of mouse down and mouse up events in OpenDoc. The diagram shows an active and inactive window. Frames are labelled F1, F2 and so on. Locations for mouse clicks are labelled a, b, c and so on.
F3 is the frame with the selection focus. F4 is selected. F8 is a background selection. F2 and F9 are frames viewed as icons.
The solid dark ovals represent intrinsic content. Though the diagram resembles a collection of page layout-type parts, the concepts explained should be generally applicable.
The table lists a number of scenarios. Each scenario consists of a mouse down or mouse up at a particular location. The table lists the frame which is the receiver of the event, the OpenDoc event type which is delivered, the embedded frame passed in the eventInfo struct, and a brief description of the action taken by the relevant part editor.
Note: The scenarios are not a sequence. Each scenario is independent, beginning with the state as shown in the diagram.
Note: For brevity, the receiver of an event is listed as a frame. Obviously it is the HandleEvent() method of the frame's part which is called. The frame and a facet are passed as parameters.
The following abbreviations are used to denote the different event types:
MD - kODEvtMouseDown
MU - kODEvtMouseUp
MDE - kODEvtMouseDownEmbedded
MDB - kODEvtMouseDownBorder
BGMD - kODEvtBGMouseDown
BGMDE - kODEvtBGMouseDownEmbedded
The inactive window could be in the same process, or be a separate document in the background. The latter case is distinguished by a (BG) in the Location column.
Unmodified Mouse Down In Active Window
Unmodified mouse down events go to the frame under the mouse, unless it is contained in a selection or bundled frame, or is viewed as an icon or thumbnail. Modified mouse down events (Shift or Command) are sent to the selection focus.
a) White Space in Inactive Frame of Active Window
F1 receives an event of type kODEvtMouseDown.
F1 responds by activating itself, and beginning a drag-selection. Activation at this point should not yet include the display of palettes. Nevertheless, the receiving part should grab the selection focus so that the active border changes, and may as well grab the other foci if it can do so without causing palettes to be displayed.
The remaining activation (showing palettes) will occur on mouse up, or when the drag-selection otherwise completes.
b) Selectable Content in Inactive Frame of Active Window
F1 receives an event of type kODEvtMouseDown.
F1 responds by activating itself, selecting the content and beginning a drag. Activation at this point should not yet include the display of palettes, unless the palette could serve as a drop destination for the part editor's own content. Nevertheless, the receiving part should grab the standard foci on mouse down, since it may never get a mouse up, or a drop, if the user drags the selection to another part. Furthermore, the destination part may just swallow the selection, and grab no foci itself. In that case F1, the receiver of the mouse down, would remain active after the drop.
c) Frame As Icon Embedded in Inactive Frame
F1 receives an event of type kODEvtMouseDownEmbedded. The embeddedFrame field of the eventInfo struct contains F2.
The same would occur if F2 were bundled or selected.
F1 responds as for b) above.
d) Active Border
F1 receives an event of type kODEvtMouseDownBorder. The embeddedFrame field of the eventInfo struct contains F3.
F1 responds as for b) above.
e) Selected or Bundled Frame
F3 receives an event of type kODEvtMouseDownEmbedded. The embeddedFrame field of the eventInfo struct contains F4 (Note: not F5). The same would occur if F4 were bundled or viewed as an icon or thumbnail.
F3 responds by detecting a drag of F4. If a drag occurs the mouseUp event is consumed. If no drag occurs, F5 will receive a mouse up and activate itself (See below).
Modified Mouse Down In Active Window
If the user shift-clicks or command-clicks in a frame which is embedded in the frame with the selection focus, then events of type kODEvtMouseDownEmbedded and kODEvtMouseUpEmbedded are delivered to the frame with the selection focus, which should extend or reduce the selection in that frame.
A shift-click or command-click on or outside the active border is an illegal operation, and OpenDoc will beep.
f) - Frame Embedded in Active Frame
F3 receives an event of type kODEvtMouseDownEmbedded with the same modifier flags. The embeddedFrame field of the eventInfo struct contains F6.
F3 responds by adding F6 to its selection (assuming it supports multiple selections).
The same thing happens with a Command-Click, and the editor should follow the standard Macintosh Human Interface Guidelines for extending contiguous and discontiguous selections.
Unmodified Mouse Up in Active Window
New in DR3: Unmodified mouse up events generally go to the frame which received the mouse down. One exception is if the mouse down occurs on a selected frame.
Note: A mouse down in a selected frame goes to the container, but the mouse up doesn't. If the container begins a drag, the mouse up is swallowed by the Drag and Drop code. If it doesn't, then the embedded part receives the mouse up, and can be activated. This allows users to activate an embedded frame with a single click, while still allowing them to readily drag selected objects without accidentally activating a frame contained within the selection.
On receiving a mouse up event, part editors should activate the frame if it is not already active.
a) b) e) f) Normal Frame (not Icon, Thumbnail or Bundled)
The frame which received a mouse down receives an event of type kODEvtMouseUp.
The frame activates itself if necessary.
c) Bundled Frame, Icon or Thumbnail
The containing frame (F1) receives an event of type kODEvtMouseUpEmbedded.
F1 responds by activating itself if necessary.
Unmodified Mouse Down In Inactive Window
Unmodified mouse down events in an inactive window go to the frame under the mouse, unless it is contained in a (background) selection or bundled frame, or is viewed as an icon or thumbnail.
If the window belongs to a background process, the event will be sent as a kODEvtBGMouseDown or kODEvtBGMouseDownEmbedded.
g) - White Space in Frame of Inactive Window
If the inactive window is in the foreground process, F7 receives an event of type kODEvtMouseDown. F7 should respond by doing nothing, waiting for the mouseUp to activate the window.
If the inactive window belongs to a background document, F7 receives an event of type kODEvtBGMouseDown. The part editor should return kODFalse from HandleEvent(), and let the process manager bring the process to the front.
See the Drag and Drop recipe for more details on this and the following three cases.
h) - Selected or Bundled Frame in Inactive Window
The containing frame (F7) will receive an event of type kODEvtMouseDownEmbedded with F8 in the embeddedFrame field of the eventInfo struct. If the window is in a background process, a kODEvtBGMouseDownEmbedded event will be sent.
F7 should respond by initiating a drag, or by doing nothing, letting the mouseUp or Process Manager activate the window as described above.
i) - Frame As Icon Embedded in Inactive Frame
The containing frame (F7) will receive an event of type kODEvtMouseDownEmbedded with F8 in the embeddedFrame field of the eventInfo struct. If the window is in a background process, a kODEvtBGMouseDownEmbedded event will be sent.
F7 should respond by initiating a drag, or by doing nothing, letting the mouseUp or Process Manager activate the window as described above.
j) - Selectable Content in Inactive Window
An event of type kODEvtMouseDown or kODEvtBGMouseDown will be sent.
F7 should respond by doing nothing, letting the mouseUp or Process Manager activate the window as described above.
Issue for HI: This seems inconsistent with i). Shouldn't both cases allow a drag or not? Are frames viewed as icons special?
Mouse Up In Inactive Window
g) h) i) j)
New in DR3: In general, mouse up events go to the frame which received the mouse down. As described earlier, one exception is if the mouse down occurs on a selected frame, in which case the mouse down goes to the containing frame.
On receiving an event of type kODEvtMouseUp or kODEvtMouseUpEmbedded in an inactive window, part editors should merely activate the window.
New in DR2: The ODWindow method Select() brings the process to the front if it is in the background.
Mouse Focus
New in DR4:
The mouse focus kODMouseFocus can be used in certain modal situations such as a polygon drawing tool. Polygons are usually drawn by clicking once for each vertex. The polygon is completed by double-clicking for the last vertex at which point the user exits the mode. The mode is also completed in other ways, such as clicking in the menu bar or switching to another window. In these cases the last line segment is typically not drawn. Between vertices, while the mouse button is up, the editor must provide feedback showing the current line segment.
Parts can implement such tools by requesting the mouse focus when the user clicks to create the first line segment. The part will then receive all mouse down or mouse up events until it relinquishes the focus. It will also receive kODEvtMouseWithin events regardless of which facet the cursor is over . kODEvtMouseEnter and kODEvtMouseLeave events are not sent.
The facet passed to HandleEvent will be the one in which the initial mouse down event occurred.
